feat: zod v4 #869

dclark27 · 2025-08-12T17:43:33Z

Upgrade to Zod v4 for compatibility with v3 and v4.

Replaces zod-to-json-schema with a temporary utility inside of mcp.ts until zod-to-json-schema supports v4.
Runs https://github.com/nicoespeon/zod-v3-to-v4 and then manual changes after the fact to clean up any remaining issues.
Includes a small zod-to-json schema patch since that does not support zod 4 yet, should be replaced once released
Small tweak to jest.config to get things running again

Note, it wasn't clear which formatter to use so some commas changed and some lines I did not intend to.

Motivation and Context

This has been a blocking issue for my team and many others. When versions mismatch across dependencies with older Zod versions, memory leaks become present and can slow or stall development.

This also will help unblock downstream dependencies, such as with vercel's AI SDK and mcp-tools.

#494
vercel/ai#7160
vercel/mcp-handler#93

How Has This Been Tested?

Ran the full test suite locally:
- 34 test suites, 669 tests, all passing (no linter errors introduced)
Validated scenarios:
- Tools with input schema: names and types appear as expected
- Tools with output schema: JSON schema produced and used for server-side validation
- Optional fields correctly omitted from required, enums produce { type: "string", enum: [...] }
Install to my Next.js app that spins up a remote MCP with tools and was able to successfully call them
Nested objects supported recursively
Platform: macOS, Node >= 18

Breaking Changes

Users will need to use Zod 3.25.76+ or Zod 4 and import from either /v3 or /v4.

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed

Additional context

domdomegg · 2025-08-13T10:30:48Z

src/server/mcp.ts

+  enum?: string[];
+};
+
+function zodToJsonSchema(schema: ZodObject<ZodRawShape>): JsonSchema {


Still need to think about this PR more broadly, e.g. what the impacts of this potentially breaking change will be.

But I think for this we could use https://zod.dev/json-schema instead?

Happy to give it a shot today!

@domdomegg
So I definitely just had a misunderstanding of how the new toJSONSchema method from Zod 4 worked -- just updated and stripped out the custom code in favor of that. Tests passed without issue. Check it out!

ihrpr · 2025-08-13T14:46:12Z

Thanks for working on this. We are preparing for Typescript V2, this potentially can be included there

dclark27 · 2025-08-13T20:37:13Z

Thanks for working on this. We are preparing for Typescript V2, this potentially can be included there

Let me know if I can help! @ihrpr

avivnakar · 2025-08-19T11:19:53Z

src/examples/server/simpleSseServer.ts

    {
-      interval: z.number().describe('Interval in milliseconds between notifications').default(1000),
-      count: z.number().describe('Number of notifications to send').default(10),
+      interval: z.number().describe('Interval in milliseconds between notifications').prefault(1000),


why is prefault preferred in this case?
as far as I understand from https://zod.dev/v4/changelog#default-updates it's about expected input type (in their example it's a string) and output type (in their example the string goes through transform to output a number)

looks like here default will work as well since input type is same as output type - number

yeah we can use default! let me get it updated. the util I used defaults to prefault to preserve default functionality so I left it as is.

dclark27 · 2025-08-19T21:25:14Z

@avivnakar / all

Updated with main, resolved conflicts, reverted to use default over prefault. I've been running since this PR went live by publishing behind our org and it's been lovely!

pterror · 2025-08-25T15:55:06Z

src/server/mcp.ts

+// Lightweight replacement for zod-to-json-schema tailored for this SDK's needs.
+// Produces a minimal JSON Schema subset: { type: "object", properties, required? }
+// Supports primitives, enums, and nested objects. Sufficient for our tool list output tests.


obsolete comment

ochafik · 2025-09-08T17:01:26Z

Hi @dclark27, thanks for your work on this!

I wonder if the v3 & v4 compatibility can be tested (and maybe documented)? Maybe adding v3 as a dev dependency and have some tests explicitly importing the /v3 paths?

ochafik

This looks good, with some reservations:

Can we provide some testing of backwards compatibility (client / server code w/ v3)
Wonder how this will interplay w/ #792 (what is the v4 equiv. of strip? ideally we'll want to merge the two PRs to see how they mesh)

JosephAnson · 2025-09-08T17:38:47Z

Just thought I'd let you know after reading the guide here (https://zod.dev/library-authors?id=how-to-support-zod-4) for library authors, you shouldn't be importing from zod/v4 for library usage, it should be zod/v4/core. There is also recommendations for having it work simultaneously with v3 and v4 of zod: https://zod.dev/library-authors?id=how-to-support-zod-and-zod-mini-simultaneously.

dclark27 · 2025-09-09T19:59:10Z

@ochafik

Two ways forward here, I can adjust this PR to include backward compatibility with v3 and go adjust his PR after it merges, or I can merge his branch into mine and tackle holistically once theirs is merged.

We can use strictObject and looseObject for interplay it looks like. https://zod.dev/v4/changelog?id=deprecates-strict-and-passthrough

For now I will start with backward compatibility in this branch and see what progress is made with #792 unless you have a strong preference.

dclark27 · 2025-09-09T23:11:29Z

cc: @ochafik @domdomegg

I have updated this branch with main and resolved conflicts. There is a blocking issue though preventing us from supporting Zod v3 and v4, which is that zod-to-json-schema does not allow 3.25 as a peer dependency.

Zod 3.23
- Fine for zod-to-json-schema library and we could use to fallback schema generation, however it is not cross compatible with zod v4
Zod 3.35
- Cross compatible with zod 4 but cannot use zod-to-json-schema for fallback schema generation due to peer dependency issue
Zod 4
- Implements z.toJsonSchema and the dependency is not required.

Check out my changes here with backwards compatibility changes and extra regression tests for v3 and v4: socotra@c1e5d38

We might be blocked until StefanTerdell/zod-to-json-schema#180 is merged. Others have published around them but I'd rather find another option.

KKonstantinov · 2025-09-11T22:44:34Z

Could the migration to zod v4 replace the usage of Ajv since Zod v4 supports json schema conversion natively?

punkpeye · 2025-09-15T00:16:09Z

Have you by any chance published this branch on npm?

dclark27 · 2025-09-16T21:56:09Z

Have you by any chance published this branch on npm?

Yep!

npm i @socotra/modelcontextprotocol-sdk

punkpeye · 2025-09-17T19:50:53Z

Thank you!

avivnakar · 2025-09-28T15:37:38Z

src/server/completable.ts

-    );
+  complete: CompleteCallback<T>
+): T & {
+  _def: (T extends { _def: infer D } ? D : unknown) & CompletableDef<T>;


first of all I want to claim that I am not a part of the mcp organization so I hope I am not a blocking phase for this feature. I really am anticipating for the SDK to support zod v4 and I want to thank you for your time and effort!

I took a little more time to further learn about zod and the SDK so I can provide some meaningful insights if possible

according to https://zod.dev/library-authors?id=how-to-support-zod-3-and-zod-4-simultaneously you can support both z3 and z4 which can make this feature (in case that the maintainers of this repo are willing) a non-breaking change so it can be part of sdk v1 rather than v2. I suggest asking the maintainers before re-implementing the whole PR of course!

besides backward compatibility, it looks like _def is a zod v3 style whereas in zod v4 it should be ._zod.def. I really am not sure about that, I assume you already stumbled upon this and I just am missing something but I'd love to hear what you have to say about this.

one thing that I am not sure about is your choice to as unknown as and the usage as in general. I suggest adding a comment that explains why this kind of type manipulation is required rather than using type guards (using simple conditions/ custom type predicates with is or maybe using zod) that will explain intentions better

I also am not sure about the completable feature and have never used it before

avivnakar · 2025-09-28T15:42:39Z

src/server/mcp.ts

+    const defLike = (field as unknown as { _def?: { typeName?: unknown } })
+      ._def;
+    if (!defLike || defLike.typeName !== McpZodTypeKind.Completable) {


again, not sure why as unknown as is required, I also suggest to use a helper function, something like

Suggested change

const defLike = (field as unknown as { _def?: { typeName?: unknown } })

._def;

if (!defLike || defLike.typeName !== McpZodTypeKind.Completable) {

if (notCompletable(field)) {

could look nicer

avivnakar · 2025-09-28T15:49:44Z

src/shared/auth.ts

-    dpop_bound_access_tokens_required: z.boolean().optional(),
-  })
-  .passthrough();
+export const OAuthProtectedResourceMetadataSchema = z.object({


I think looseObject replaces the removed passthrough

Suggested change

export const OAuthProtectedResourceMetadataSchema = z.object({

export const OAuthProtectedResourceMetadataSchema = z.looseObject({

avivnakar · 2025-09-28T15:51:18Z

src/shared/auth.ts

-    refresh_token: z.string().optional(),
-  })
-  .strip();
+export const OAuthTokensSchema = z.object({


https://zod.dev/v4/changelog#deprecates-strict-and-passthrough

Suggested change

export const OAuthTokensSchema = z.object({

export const OAuthTokensSchema = z.strictObject({

also in 184 194 211 219

dclark27 added 5 commits August 11, 2025 17:29

chore: initial upgrade, broken tests

6db0e68

chore: replace zod-to-json-schema temporarily

08513d3

chore: remove dependency that is unused

3b28aac

chore: fix formatting of mcp.test

1cc8c7b

chore: add commas

9b178b7

dclark27 requested review from a team as code owners August 12, 2025 17:43

dclark27 requested review from ochafik and domdomegg August 12, 2025 17:43

Merge branch 'main' into zod-v4

9298723

dclark27 changed the title ~~Zod v4~~ feat: zod v4 Aug 12, 2025

domdomegg reviewed Aug 13, 2025

View reviewed changes

ihrpr added this to the v2 milestone Aug 13, 2025

chore: skip custom json schema generation

aca892b

Rain120 mentioned this pull request Aug 14, 2025

feat: upgrade zod to v4 antvis/mcp-server-chart#163

Open

Merge branch 'main' into zod-v4

e2d351c

avivnakar reviewed Aug 19, 2025

View reviewed changes

dclark27 added 2 commits August 19, 2025 14:21

Merge remote-tracking branch 'upstream/main' into zod-v4

2010203

chore: use default instead of "prefault"

8531d8e

pterror reviewed Aug 25, 2025

View reviewed changes

dclark27 added 4 commits August 25, 2025 09:19

Merge branch 'main' into zod-v4

1461fa2

chore: remove comment

9cf8b2e

Merge branch 'main' into zod-v4

5a761b5

Merge branch 'main' into zod-v4

30fb023

dclark27 mentioned this pull request Sep 3, 2025

Migrating to Zod v4, marking as peer dependency, and removing zod-to-json-schema #914

Draft

9 tasks

ochafik mentioned this pull request Sep 8, 2025

MCP SDK v1.17.5 Incompatible with Zod v4 - Breaking Changes #925

Open

ochafik requested changes Sep 8, 2025

View reviewed changes

ochafik mentioned this pull request Sep 8, 2025

Make zod types strip (default) instead of passthrough #792

Open

Merge remote-tracking branch 'upstream/main' into zod-v4

3cd0546

jdwyah mentioned this pull request Sep 12, 2025

McpError: MCP error -32603: keyValidator._parse is not a function #291

Closed

Jacse mentioned this pull request Sep 16, 2025

chore: allow zod 4 peer StefanTerdell/zod-to-json-schema#180

Open

Merge branch 'main' into zod-v4

5a64ed1

chore: update to zod latest

ab26df8

wandri mentioned this pull request Sep 24, 2025

Support for Zod 4 rekog-labs/MCP-Nest#123

Open

felixweinberger force-pushed the main branch from 0845a57 to c94ba4b Compare September 25, 2025 14:53

avivnakar reviewed Sep 28, 2025

View reviewed changes

	export const OAuthProtectedResourceMetadataSchema = z.object({
	export const OAuthProtectedResourceMetadataSchema = z.looseObject({

	export const OAuthTokensSchema = z.object({
	export const OAuthTokensSchema = z.strictObject({

feat: zod v4 #869

Are you sure you want to change the base?

feat: zod v4 #869

Conversation

dclark27 commented Aug 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Additional context

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dclark27 Aug 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ihrpr commented Aug 13, 2025

Uh oh!

dclark27 commented Aug 13, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dclark27 commented Aug 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ochafik commented Sep 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ochafik left a comment

Choose a reason for hiding this comment

Uh oh!

JosephAnson commented Sep 8, 2025

Uh oh!

dclark27 commented Sep 9, 2025

Uh oh!

dclark27 commented Sep 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

KKonstantinov commented Sep 11, 2025

Uh oh!

punkpeye commented Sep 15, 2025

Uh oh!

dclark27 commented Sep 16, 2025

Uh oh!

punkpeye commented Sep 17, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

dclark27 commented Aug 12, 2025 •

edited

Loading

dclark27 Aug 13, 2025 •

edited

Loading

dclark27 commented Aug 19, 2025 •

edited

Loading

ochafik commented Sep 8, 2025 •

edited

Loading

dclark27 commented Sep 9, 2025 •

edited

Loading